Getting-Device-State

With OmniCore, you can control a device by modifying its configuration. A device configuration is an arbitrary, user-defined blob of data. After a configuration has been applied to a device, the device can report its state to OmniCore.

Device configuration works differently in the MQTT and HTTP bridges. See below for details.

For more information, see Devices, Configuration, and State.

Limits

Configuration updates are limited to 1 update per second, per device. However, for best results, device configuration should be updated much less often — at most, once every 10 seconds.

The update rate is calculated as the time between the most recent server acknowledgment and the next update request.

Reporting device state

MQTT

To report state to OmniCore through the MQTT bridge, publish messages to the /REGISTRY_ID/DEVICE_ID/state MQTT topic. You can select a Cloud Pub/Sub topic to store state events when you create or update a registry.

For more details, see Publishing over the MQTT bridge.

HTTP

To report state to OmniCore through the HTTP bridge, devices should use a setState request. The binary state data is passed in the body of the request as a base64-encoded string.

For more details, see Publishing over the HTTP bridge.

Getting device state data

This section explains how to get the state data that's reported to OmniCore by devices. (Devices themselves cannot read state data from the cloud.)

State data is returned in binary format. State data may have a different structure than the configuration data that triggers the state change.

For example, suppose you have a device with several fans. Your configuration data might be a JSON object containing a simple Boolean that enables or disables cooling:

Example of configuration data

{
  'cooling': true
}

But the device's state data might include diagnostic information, as well as the fan data that you'd expect to see in response to a 'cooling' change:

Example of state data

{
  'fan1_target_rpm': 1000,
  'fan2_target_rpm': 1200,
  'firmware_version': '1.2.3b'
}

The device's firmware_version is not related to the configuration data, but the device returns the full internal representation of its state. This example illustrates how device state can be useful for debugging in general, as well as for confirming that devices have acknowledged specific configurations.

You can get device state data using a Cloud Pub/Sub topic, Cloud Platform Console, the OmniCore API. Get Device States

PubSub Topic

OmniCore retains state data in storage. You can also configure an optional state notification Cloud Pub/Sub topic in each device registry, via Cloud console, or the API. This topic can be the same as or different from the telemetry event topic.

State data is published to Cloud Pub/Sub on a best-effort basis: if publication to the topic fails, it will not be retried. If no topic is defined, device state updates are still persisted internally by OmniCore, but only the last 10 states are retained.

Console

1. Go to the Registries page in console.
2. Click the ID of the registry for the device.
3. In the registry menu on the left, click Devices.
4. Click the ID of the device to go to the Device details page.
5. Click Configuration & state history. Use the checkboxes to display configuration history, state history, or both. By default, both are shown.
   • A green checkmark indicates that the device has acknowledged the configuration (MQTT only).
   • A yellow warning symbol indicates that the device has not yet acknowledged the configuration (MQTT only).
   • Click a row to get the full configuration or state data in JSON, as well as the timestamp and version.
6. Click Compare to compare the configuration data with the state data. This view can help you debug configurations and, if you are using MQTT, make sure devices have acknowledged specific configuration versions. (The HTTP bridge does not support acknowledgment of configurations.)

Use the Device states list method to get the most recent device states (up to 10). Each Device resource has a DeviceState field that contains the state most recently received from the device. The DeviceRegistry resource has a StateNotificationConfig field that can be used to specify a state notification Cloud Pub/Sub topic when creating or updating a registry.